Welcome to ‘Documenting and Testing REST
APIs with Swagger’. After watching this video, you will be able
to document your REST API using Swagger, and test your REST API using Swagger. APIs specify an interface and connect different
systems providing them with consistent communication. And API documentation is like a reference
manual containing instructions on effectively using and integrating systems. Swagger saves time writing API documentation
by running through the OpenAPI specification to ensure you meet the guidelines. Swagger allows you to describe the structure
of your APIs so that machines can read them. With the API’s structure, Swagger automatically
builds engaging UI and interactive API documentation. This structure is defined in a JSON or YAML
file that adheres to OpenAPI specifications. Now initially, APIs were not meant for self-service
consumption. They were data-driven and solved a few special
use cases of connection and communication. Whereas the OpenAPI Specification defines
a standard, language-agnostic interface to RESTful APIs. The specification is language agnostic and
human and machine-readable. In addition, it allows people and computers
to discover and understand the capabilities of a service without requiring access to source
code, additional documentation, or inspection of
network traffic. It defines all the operations that your API supports, the required parameters and the expected return, and required API authentication. And it even defines things like terms of service, contact information, and the license information for the exposed
API. Now Flask enables exposure to Python functions
as APIs. Flask Swagger UI improves upon its capabilities
by allowing you to describe and visualize the REST APIs. To introduce the Swagger UI to your application,
you need the Flask blueprint ‘Flask-swagger-ui’. The command ‘pip install Flask-swagger-ui’
will add the Swagger UI to your Flask application by using pip. First, you need to import the ‘swagger_ui_blueprint’,
which will help you create the Swagger UI using Flask. Then you define the basic configuration, which
consists of the path where the Swagger will be available. You have kept it under the products/docs path
in this example. The second argument displays where the swagger
file is served. And the name you want to give to this Swagger. You then need to register this blueprint with
the app for Flask. Swagger.JSON holds the definition and characteristics
of your API in the form of a JSON file. You need to expose this file as well with
your API. So, you need a route that will serve your
static swagger.JSON file. Swagger is a JSO file and requires some basic
configurations to be present. Here in this example, you are creating the
product microservice API swagger and providing the model and path for getting the products
list. And defining the properties of the Product
object. You now have an API definition and Swagger. You can use the UI to test your API and that is
the key benefit of using Swagger. In addition, it allows consumers to get more
details about your API, the supported functions, requests, and responses. It also displays content from the product
info section. It displays the only available method, a GET
to retrieve all products. You can then execute that endpoint and see
the outcome, which, in this case, is the list of products. In this video, you learned that Swagger helps you document your APIs, the OpenAPI specification is a standard way
of representing your APIs, and Swagger provides a mechanism for testing
your APIs.